fix(runtime): classify provider capacity errors - #3365

Heads up — this is currently conflicting with main, so I can't review or merge it as-is. Your CI is fully green, so it really is just the base that's behind.

One thing worth knowing: #3397 landed on 2026-08-22 and added ASF license headers across ~2685 files, so the rebase will touch more than you'd expect, and any file you add now needs a header (npm run write:asf-headers).

Ping me once it's rebased and I'll pick it up.

@Astro-Han PR #3365 已完成 rebase，当前基于最新 main（f19eede03），远端 head 为 4f00034。冲突已解决，构建和相关功能测试已通过；当前 PR 状态为 MERGEABLE，剩余 BLOCKED 原因为 REVIEW_REQUIRED，请继续处理。

Independent review of 4f000347786612c0b1b85af27ffa970bd85d07e4. Two [P2]s, both inline, both about ordering rather than logic — every individual rule here is right; two of them are in the wrong place relative to their neighbours.

• fix(runtime): classify provider capacity errors #3365 (comment) — the capacity branch runs before the partial-output and successful-tool guards, so a Turn that already did work is told to retry, and retrying can re-run tool side effects.
• fix(runtime): classify provider capacity errors #3365 (comment) — free-text abort and the generic 402/429/401/403 fallbacks outrank the exact resource-exhausted code, so a wrapped error loses its capacity classification (and in the 429 case, its retryability).

The bigger question is not in this diff: duplicate authority with #2521

Inside this branch there is no second classifier — it plugs into the existing classification, retry, wire, and Desktop presentation chain. Of the 18 files, 7 are tests and the other 11 are real core-type / runtime / strict-wire / Desktop boundaries. Deleting files is not the simplification available here.

The actual duplication is with #2521, which is open on the same baseline f19eede0:

• 13 of 18 files overlap.
• Both raise the compatibility epoch from 39 to 40.
• git merge-tree produces 7 content conflicts — classifier, model adapter, Desktop presentation, Runtime Host protocol/handshake.
• fix(runtime): distinguish usage limits from auth errors #2521 has already established ProviderFailureResult as a single provider-failure authority.

That is not a third finding against this diff, but it is a merge-order and design gate: two implementations of the same concept should not both land. If #2521 is the intended authority, the low-entropy path is for this PR to rebase and contribute ProviderCapacity into that one taxonomy. If this one lands first, #2521 has to rebase and absorb the concept. Either order works — doing neither is the failure mode.

Candidates raised and withdrawn

• "Classify the generic resource_exhausted as capacity too" — in Google/gRPC that commonly means quota; restricting to the xAI hyphenated form is evidence-based. Withdrawn.
• "Fold the capacity retry reason back into provider_unavailable to avoid the epoch bump" — that discards the stable semantics this PR exists to establish, at the exact moment the user can see it. Withdrawn.
• "18 files means the change is too broad" — 7 tests plus 11 genuine contract boundaries. Withdrawn; the overlap to remove is with fix(runtime): distinguish usage limits from auth errors #2521, not within this diff.

State of the head

• Fresh REST reports mergeable=false / dirty against origin/main=2e5fe9c5; local merge-tree reproduces the conflict in packages/runtime-host/src/__tests__/protocol.test.ts. The 01:42 UTC comment saying MERGEABLE is stale.
• check-runs on this head: 0. The only workflow run (32609206478) is terminal action_required with 0 jobs — the tests never started. Not green; never run.
• All three review endpoints were read separately. The only substantive prior review is bound to the older commit 2a8a0b9e, and its findings (underscore quota, malformed Retry-After, test-object reuse, lost retry reason) are addressed on this head. Neither P2 above is a restatement of those.
• Local verification: clean worktree, npm ci fine, Desktop build:with-deps fine, 150/150 relevant tests pass. Those 150 do not cover either mixed-state path above — which is the point.

Blind line: provisional judgment sealed before any existing review was read. Reviewed at 2026-08-23 13:12 UTC. No overall verdict offered.

Both [P2]s are fixed on the new head 8ebbb02953a69057814a3969eda1b582577463da. I re-derived them rather than taking the rebase on trust — the ordering is now correct in both places.

Presentation — capacity moved below the two guards it was jumping:

if (input.partialOutputRetained) return { action: 'continue',     label: copy.partial };
if (input.toolActivityCount > 0) return { action: 'inspect_tool', label: copy.toolRecord };
if (lower === 'provider_capacity') return { action: 'retry',      label: copy.capacity };

A Turn that already retained output or ran a tool successfully now gets continue / inspect tool instead of retry, so the path that could re-run completed tool side effects is closed.

Classification — the exact structured code now precedes the weak wrapper evidence:

if (PROVIDER_CAPACITY_CODES.has(normalizedCode) || structuredCodes.some(...)) return 'ProviderCapacity';
...
if (text.includes('abort')) return 'Abort';
if (statusCode === '429' || code === '429') return 'RateLimit';

{statusCode: 429, data: {error: {code: 'resource-exhausted'}}} now classifies as ProviderCapacity rather than RateLimit, which also stops it from losing retryable when no Retry-After is present. Context-overflow structured evidence was promoted alongside it, which is consistent — structured provider identifiers ahead of ambiguous transport facts, applied uniformly rather than only where it was reported.

Two things still open, neither of them mine to close:

1. The fix(runtime): distinguish usage limits from auth errors #2521 overlap stands and is unaffected by a rebase: 13 of 18 files in common, 7 content conflicts, and both PRs raising the compatibility epoch. That remains a merge-order decision — whichever lands first, the other must absorb the concept rather than duplicate it.
2. This head arrived at action_required with zero jobs, same as the last one. I have approved the run so it can report. Not green yet — never run yet.

I will re-check once CI reports.

To clarify the integration recommendation for #2521 and this PR:

These are not merely adjacent changes. #2521 establishes a broader provider-failure authority (ProviderFailureResult) across the same runtime classification, runtime-host protocol, Desktop presentation, and test surfaces that #3365 changes for ProviderCapacity. Both also evolve compatibility/protocol behavior.

I recommend choosing one authority before merging:

• If fix(runtime): distinguish usage limits from auth errors #2521 is intended to land, rebase fix(runtime): classify provider capacity errors #3365 onto it and express ProviderCapacity through ProviderFailureResult.
• If fix(runtime): distinguish usage limits from auth errors #2521 is not landing first, merge fix(runtime): classify provider capacity errors #3365, then rebase fix(runtime): distinguish usage limits from auth errors #2521 and have it absorb ProviderCapacity, the capacity-specific recovery behavior, and the protocol epoch change.

Landing both independently would leave two classification authorities and makes divergent retry/recovery behavior and protocol conflicts likely. This is an architectural merge-order decision rather than a routine conflict to resolve after both land.

Fixed in c001f6b.

durableProviderErrorClass() now preserves structured ProviderCapacity evidence before HTTP fallback classification, matching the existing ContextLength treatment. Added durable-diagnostic regression coverage for resource-exhausted wrapped by both HTTP 429 and 503. The targeted runtime classification suite passes (12/12).

Hi — thanks for c001f6b85; the durableProviderErrorClass() change reads right.

Heads-up that this branch now conflicts with current main and can't be merged as-is. I tested a rebase locally in a throwaway worktree (your branch was untouched); it stops on:

• packages/runtime-host/src/protocol/index.ts
• packages/runtime-host/src/__tests__/protocol.test.ts

Worth knowing what that first conflict is, because it isn't mechanical: it's RUNTIME_HOST_COMPATIBILITY_EPOCH. Every protocol-changing PR increments that single counter and prepends a line to the changelog comment above it, so any two protocol PRs in flight at once collide there by construction. main has since moved the epoch past the value your branch sets.

Resolving it means re-deriving your epoch bump on top of whatever main is at now, and keeping your changelog line alongside the ones that landed meanwhile — i.e. it's a deliberate "is my compatibility claim still accurate relative to the current epoch?" decision, which is exactly why it isn't auto-mergeable.

git fetch upstream && git rebase upstream/main
# resolve, then
git push --force-with-lease

Once the branch is conflict-free and CI is green on the new head, I'll pick the review back up.

AI-assisted maintenance note, not a review. It does not count as the required human review under CONTRIBUTING.md §Review.

Rebased and resolved in 569f7b066.

The branch is now based on current apache/maka:main (efddab2fb) and is conflict-free. Since main already uses compatibility epoch 41, the provider-capacity retry protocol change is now recorded as epoch 42, while retaining the epoch 41 and 40 changelog entries. The protocol assertion was updated accordingly.

Verification after a clean workspace build:

• npm run build passed
• Runtime Host protocol tests: 43/43 passed
• Runtime provider classification tests: 12/12 passed

The rebased head was pushed with --force-with-lease; please rerun CI and resume review.